@wordpress/keycodes

What is @wordpress/keycodes?

@wordpress/keycodes is a utility package that provides constants and helper functions for working with keyboard key codes. It is particularly useful for handling keyboard events in a consistent manner across different browsers and environments.

What are @wordpress/keycodes's main functionalities?

Keycode Constants

The package provides constants for common key codes, making it easier to reference and use them in your code without having to remember the numeric values.

const { ENTER, ESCAPE } = require('@wordpress/keycodes');
console.log(ENTER); // Outputs: 13
console.log(ESCAPE); // Outputs: 27

isKeyboardEvent

This helper function checks if a given keyboard event matches a specified key. It simplifies the process of handling specific key events.

const { isKeyboardEvent } = require('@wordpress/keycodes');
const event = new KeyboardEvent('keydown', { keyCode: 13 });
console.log(isKeyboardEvent(event, 'enter')); // Outputs: true

getKeycodeByKey

This function returns the keycode for a given key name, providing a convenient way to map key names to their corresponding key codes.

const { getKeycodeByKey } = require('@wordpress/keycodes');
console.log(getKeycodeByKey('Enter')); // Outputs: 13

Other packages similar to @wordpress/keycodes

keycode

The 'keycode' package provides a simple utility for converting between keyboard key names and their corresponding key codes. It offers similar functionality to @wordpress/keycodes but is more focused on the conversion aspect rather than providing a comprehensive set of utilities.

mousetrap

Mousetrap is a library for handling keyboard shortcuts in JavaScript. While it offers more advanced features for binding and handling keyboard shortcuts, it also includes utilities for working with key codes, making it a more feature-rich alternative to @wordpress/keycodes.

hotkeys-js

Hotkeys-js is a lightweight library for handling keyboard shortcuts. It provides a simple API for binding and unbinding keyboard events, and includes utilities for working with key codes. It is similar to @wordpress/keycodes but with a focus on keyboard shortcuts.

README

Keycodes

Keycodes utilities for WordPress, used to check the key pressed in events like onKeyDown. Contains keycodes constants for keyboard keys like DOWN, UP, ENTER, etc.

Installation

Install the module

npm install @wordpress/keycodes --save

This package assumes that your code will run in an ES2015+ environment. If you're using an environment that has limited or no support for such language features and APIs, you should include the polyfill shipped in @wordpress/babel-preset-default in your code.

Usage

Check which key was used in an onKeyDown event:

import { DOWN, ENTER } from '@wordpress/keycodes';

// [...]

onKeyDown( event ) {
	const { keyCode } = event;

	if ( keyCode === DOWN ) {
		alert( 'You pressed the down arrow!' );
	} else if ( keyCode === ENTER ) {
		alert( 'You pressed the enter key!' );
	} else {
		alert( 'You pressed another key.' );
	}
}

API

ALT

Keycode for ALT key.

BACKSPACE

Keycode for BACKSPACE key.

COMMAND

Keycode for COMMAND/META key.

CTRL

Keycode for CTRL key.

DELETE

Keycode for DELETE key.

displayShortcut

An object that contains functions to display shortcuts.

Usage

// Assuming macOS:
displayShortcut.primary( 'm' );
// "⌘M"

Type

• WPModifierHandler<WPKeyHandler<string>>Keyed map of functions to display shortcuts.

displayShortcutList

Return an array of the parts of a keyboard shortcut chord for display.

Usage

// Assuming macOS:
displayShortcutList.primary( 'm' );
// [ "⌘", "M" ]

Type

• WPModifierHandler<WPKeyHandler<string[]>>Keyed map of functions to shortcut sequences.

DOWN

Keycode for DOWN key.

END

Keycode for END key.

ENTER

Keycode for ENTER key.

ESCAPE

Keycode for ESCAPE key.

F10

Keycode for F10 key.

HOME

Keycode for HOME key.

isAppleOS

Return true if platform is MacOS.

Parameters

• _window Window?: window object by default; used for DI testing.

Returns

• boolean: True if MacOS; false otherwise.

isKeyboardEvent

An object that contains functions to check if a keyboard event matches a predefined shortcut combination.

Usage

// Assuming an event for ⌘M key press:
isKeyboardEvent.primary( event, 'm' );
// true

Type

• WPModifierHandler<WPEventKeyHandler>Keyed map of functions to match events.

LEFT

Keycode for LEFT key.

modifiers

Object that contains functions that return the available modifier depending on platform.

Type

• WPModifierHandler< ( isApple: () => boolean ) => WPModifierPart[]>

PAGEDOWN

Keycode for PAGEDOWN key.

PAGEUP

Keycode for PAGEUP key.

rawShortcut

An object that contains functions to get raw shortcuts.

These are intended for user with the KeyboardShortcuts.

Usage

// Assuming macOS:
rawShortcut.primary( 'm' );
// "meta+m""

Type

• WPModifierHandler<WPKeyHandler<string>>Keyed map of functions to raw shortcuts.

RIGHT

Keycode for RIGHT key.

SHIFT

Keycode for SHIFT key.

shortcutAriaLabel

An object that contains functions to return an aria label for a keyboard shortcut.

Usage

// Assuming macOS:
shortcutAriaLabel.primary( '.' );
// "Command + Period"

Type

• WPModifierHandler<WPKeyHandler<string>>Keyed map of functions to shortcut ARIA labels.

SPACE

Keycode for SPACE key.

TAB

Keycode for TAB key.

UP

Keycode for UP key.

ZERO

Keycode for ZERO key.

Contributing to this package

This is an individual package that's part of the Gutenberg project. The project is organized as a monorepo. It's made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to npm and used by WordPress as well as other software projects.

To find out more about contributing to this package or Gutenberg as a whole, please read the project's main contributor guide.